home *** CD-ROM | disk | FTP | other *** search
/ Video Toaster 4.3 / Video Toaster v4.3.iso / 4.2 / programs / documentation / arexx / switcherarexx.doc < prev    next >
Text File  |  1998-04-16  |  17KB  |  390 lines
  1.              Video Toaster Switcher Arexx Manual   4/20/95
  2.  
  3. **********************************************************************
  4. Update for 4.04 on 6/6/95 - D. Wolf
  5.  
  6. See changes to following functions:
  7.  
  8. FMLD, FMSV - Framestore load and save by filename instead of xxx.FS.yyyy
  9. GROF, GRON - Error checked for validity.
  10. QUIT       - BROKEN!!!  DO NOT USE!  Will be fixed.
  11.  
  12. A number of functions have been REMOVED!  They are meaningless in the
  13. new Toaster/Flyer software environment (releases >3.5).  The removed
  14. functions could have been potentially harmful if run.  As a reminder to
  15. all you ARexx programmers to CHANGE your programs, all these functions
  16. now return an ARexx '10' error code - likely to stop your ARexx script
  17. dead so you'll notice them and change your programs!  Calling these
  18. removed functions is completely harmless now, but you'll just get ARexx
  19. error returns from them anyhow.
  20.  
  21. Docs for some of these functions were correctly removed from this file
  22. some time ago, but the functions were still there and dangerous.
  23.  
  24. The 27 REMOVED functions are:
  25.  
  26.         PAGE, BKLD
  27.         CHGR, CKGD, RDGD, WTGD
  28.         PJLD, PJCK, PJDV, PJSV, PJDL, PJRN, PJXI, PJNM, PJMK, PJBD
  29.         FSDV, FSNM, FSMK, FSCK, FSBD, FSCT
  30.         FMDL, FMRN, FMXI
  31.         KEYP, KEYN
  32.  
  33. For example, CHGR used to let you select a different effects 'grid' -
  34. complete nonsense in the newer Toaster/Flyer environment.
  35.  
  36. ***********************************************************************
  37.  
  38.  
  39.  
  40.  
  41.  
  42.         Note about ARexx:  The Video Toaster is compatible with the ARexx
  43. programming language.  However, due to the complex and technical nature of
  44. programming, users of ARexx cannot be supported by NewTek Technical
  45. Support.  Its inclusion is intended primarily for developers, programmers,
  46. and advanced users who are familiar and comfortable with programming
  47. concepts.  Commands are subject to change without prior notice.
  48.  
  49.         The Switcher Arexx interface has been implemented as a function host,
  50. rather than the more common command host interface (e.g.  ToasterPaint).
  51. Arexx function hosts are initialized using the addlib() function with the
  52. name of the host or library.  The name of the switcher host is
  53. 'ToasterARexx.port'  and it is case-sensitive.  ARexx messages sent to the
  54. Switcher must be in function call format.  This means that all commands
  55. must be given as arguments to the function Switcher(), rather than being
  56. sent as direct commands to an ARexx command host.  If the switcher command
  57. has any parameters, then they too must be given as arguments to Switcher()
  58. or the command will fail.  Furthermore, all parameters should be uppercase.
  59. Unless otherwise noted, all function commands return 0 if they were
  60. sucessfully executed, and 10 if a failure occurred.  ARexx messages will
  61. only be accepted and processed when the main Switcher control panel is
  62. active.  At other times, ARexx messages will be accepted and will remain in
  63. the Switcher's ARexx message port queue until the primary switcher control
  64. panel is active, at which point they will execute.
  65.  
  66.         Most of the commands that directly impact the Switcher will also show up on
  67. the Switcher interface.  Almost all ARexx commands that impact the Switcher
  68. behave exactly like their corresponding manual user interface functions
  69. from the Switcher interface.  In particular, they are restricted by the
  70. active controlling effect as to whether or not their requested function
  71. will be granted.  If an ARexx command function is aborted by a controlling
  72. effect, an OK return code may still be returned.  In the case of a failure
  73. code, the current Switcher settings remain unchanged.
  74.  
  75. Arexx Command Set:
  76.  
  77.         Switcher( AUTO )
  78. This command will invoke an AUTO transition.
  79.  
  80.         Switcher( UATO )
  81. This command performs an un-auto, the equivalent of a Shift-Spacebar action
  82. to reverse a partially transitioned effect back off screen.
  83.  
  84.         Switcher( TBAR, <TBar level> )
  85. This command will invoke a TBar jump movement to the specified level
  86. (0-511).  A failure code will be returned if the level argument is invalid.
  87.  
  88.         Switcher( TAKE )
  89. This command will invoke a TAKE.
  90.  
  91.         Switcher( SLOW )
  92.         Switcher( MEDM )
  93.         Switcher( FAST )
  94.         Switcher( SVAR )
  95. The above commands set the speed active for the transition that is
  96. currently in effect. SVAR sets the effect to the last duration chosen with
  97. the variable speed selector. You MUST make sure the effect supports variable
  98. speeds bad things can and WILL happen.
  99.  
  100.         Switcher( NOPR )
  101. This command is a NOP.
  102.  
  103.         Switcher( FRES )
  104. This command resets the frame base count to the moment this command was
  105. processed.
  106.  
  107.         Switcher( WAIT, <Frame count> or GPI )
  108. This command can wait for either a specified frame count or for a GPI
  109. trigger.  If 'GPI'  is the specified argument, this function will wait for
  110. a GPI trigger to occur before continuing.  The trigger can be either a
  111. positive or negative trigger.  In the case of GPI triggering being
  112. disabled, this function will become a NOP.  If 'GPI'  is not the specified
  113. argument, then the argument is assumed to be a digit field specifying a
  114. frame count.  In this case the command will wait until the specified frame
  115. count from the last frame base count is reached.  In the case of specified
  116. frame count already exceeded, this function will return immediately.
  117.  
  118.         Switcher( CLIP, <Clip level> )
  119. This command will invoke a Clip jump movement to the specified level
  120. (0-257).  A failure code will be returned if the level argument is invalid.
  121.  
  122.         Switcher( KEYM )
  123. This command toggles the current key mode state of the Switcher.
  124.  
  125.         Switcher( M001 )
  126.         Switcher( M002 )
  127.         Switcher( M003 )
  128.         Switcher( M004 )
  129.         Switcher( MDV1 )
  130.         Switcher( MDV2 )
  131.         Switcher( MBKG )
  132. The above commands select the specified video source for the Main output.
  133.  
  134.         Switcher( P001 )
  135.         Switcher( P002 )
  136.         Switcher( P003 )
  137.         Switcher( P004 )
  138.         Switcher( PDV1 )
  139.         Switcher( PDV2 )
  140.         Switcher( PBKG )
  141. The above commands select the specified video source for the Preview
  142. output.
  143.  
  144.         Switcher( O001 )
  145.         Switcher( O002 )
  146.         Switcher( O003 )
  147.         Switcher( O004 )
  148.         Switcher( ODV1 )
  149.         Switcher( ODV2 )
  150.         Switcher( OBKG )
  151. The above commands select the specified video source for the Overlay
  152. output.
  153.  
  154.  
  155.         Switcher(GOCG)
  156.         Switcher(GOLD)
  157.         Switcher(GOSA)
  158. These commands are now obsolete.  They have been left in for compatibility
  159. reasons, but they do nothing.
  160.  
  161.         Switcher(STAT,<Command>)
  162. This command returns information about the status of the Switcher.  The
  163. return value depends on which command is used.  The possible commands are:
  164.  
  165.                 MAIN    Return status of the Program (main) row.  The binary representation
  166.             of the number returned will have a bit set for which input is
  167.             selected on the Program row.  Thus if input 1 is selected, the
  168.             number returned will be 1 (binary 00000001).  Similarly, input 3
  169.             would yield 8 (binary 00000100), DV2 would yield 64 (binary 00100000),
  170.             as it is the sixth button on the row, and fills only the sixth bit
  171.             (from the right) in the binary rep. of the returned value.
  172.  
  173.                 PREV            Return status of the Preview row in the same format as MAIN
  174.  
  175.                 OVLY            Return status of the Overlay row in the same format as MAIN
  176.  
  177.                 FREZ            Return status of the Freeze button: 0 for live video, ~0 for frozen video
  178.  
  179.                 TEXT            Return contents of popup menu in quick access panel
  180.  
  181.                 TBAR            Return T-Bar position (0-511)
  182.  
  183.                 KEYM            Return Key Mode ('BLACK', 'WHITE', or 'OFF')
  184.  
  185.                 CLIP            Return clip level (0-257, 0 and 257 are off)
  186.  
  187.                 SPED            Return current speed setting.  The number returned is a 16-bit value
  188.             whose lowest 2 bits indicate which preset speed is in effect (M=00,
  189.             F=01, V=10, and S=11).  The remaining 14 bits will hold the variable
  190.             speed.  If the 16 bit value is all 1s or 0s (i.e. -1 or 0), it means
  191.             variable speeds won't work with that particular effect.
  192.  
  193.                 FCNT            Return frame count for current effect (0-9999 frames)
  194.  
  195.                 KNUM            Return number in quick access panel
  196.  
  197.                 FXNM            Return the effect name for the current effect
  198.  
  199.                 INFO    Current numeric keypad selection (SA, LD, CG).
  200.  
  201.                 BACK    Current Background color
  202.  
  203.                 BORD    Current Border color
  204.  
  205.                 TERM    Current termination settings returned as a number whose lowest
  206.             4 bits represent the state of the four input terminators (input 4
  207.             is least significant bit, input1 most significant bit).
  208.  
  209.                 SGPI    Current GPI mode (POS,NEG,OFF)
  210.  
  211.                 FACE    Number of monitors (2 or 3)
  212.  
  213.  
  214.         Switcher(FMLD,volume:filename)
  215. This command loads the contents of the frame buffer selected on the preview
  216. bus from the named volume:filename.
  217.  
  218.         Switcher(FMSV,volume:filename,1)        1-field save
  219.         Switcher(FMSV,volume:filename,4)        4 field save
  220.         Switcher(FMSV,volume:filename)          4 field save
  221. This command saves the contents of the frame buffer selected on the preview
  222. bus to the named volume:filename.  If the last argument is 1, only 1 field
  223. of video will be saved, if that argument is 4, or is absent a standard 4-field
  224. save will occur.
  225. Note: this will save the framestore in the format volume:filename.  This
  226. command used to use a 0 to denote a 1-field save, now it uses 1 instead.
  227. Anything other than a 1 will cause a 4-field save.
  228.  
  229.         Switcher( TOWB )
  230. This command will pop the WorkBench screen up to the front and disables the
  231. Switcher/Toaster system.  This function will return a failure code if
  232. WorkBench could not be opened.
  233.  
  234.         Switcher( TOSW )
  235. This command will pop the Switcher screen up to the front and enable the
  236. Switcher/Toaster system.
  237.  
  238.         Switcher( DOEN )
  239. This command will do an "Enter" key on the numeric keypad.  This would be
  240. used to pre-load a selected effect.
  241.  
  242.         Switcher( QUIT )
  243. This command will completely shut down the Switcher/Toaster system upon its
  244. arrival.  All Switcher/Toaster resources will be freed and the program
  245. exited.
  246. NOTE:  This command IS BROKEN!!!
  247.  
  248.         Switcher( BACK , <Index # or -1> [, <Custom BG color>] )
  249. This command will select the specified matte (background) color either from
  250. indexing the current config slice matte color FGs (0-8) or a specified
  251. custom matte color if the index is specified as -1.  Custom color
  252. specifications have a valid range of 0-4096.  If you want to directly
  253. specify snow, specify your custom color as a negative 16 bit word value.
  254.  
  255.         Switcher( BORD , <index #> )
  256. This command will select the specified border color via the index specified
  257. for the current config slice border color FGs (0-7).
  258.  
  259.         Switcher( KOFF )
  260.         Switcher( KBLK )
  261.         Switcher( KWHT )
  262. The above commands forces the Key mode to be off, on with black enabled,
  263. and on with white enabled respectively.  Issuing this command does not
  264. guarantee that the key mode will be forced to the desired mode.  If it
  265. doesn't work, the function will return a failure code.
  266.  
  267.         Switcher( LVID )
  268.         Switcher( FVID )
  269. The above commands forces the Video mode to be live or frozen respectively.
  270. Issuing this command does not guarantee that the video mode will be forced
  271. to the desired mode.  If it doesn't work, the function will return a
  272. failure code.
  273.  
  274.         Switcher( NOMO )
  275. The above command does a frame capture along with motion removal.
  276.  
  277.         Switcher( SGPI, <OFF|POS|NEG> )
  278. The above command sets up the Switcher GPI trigger system.  'OFF'  disables
  279. the system, 'POS'  enables the system for positive GPI triggers, and 'NEG'
  280. enables the system for negative GPI triggers.  The changes to the Switcher
  281. GPI trigger system made by this function WILL NOT be reflected in the
  282. HardSets file.  Tech note:  GPI input occurs on pin 6 of the second
  283. gameport (bit 7 of CIAA port A).
  284.  
  285.         Switcher( DISW )
  286.         Switcher( ENSW )
  287. The above commands are for disabling/enabling return of control from the
  288. ARexx environment back to the Switcher.  The primary use of these commands
  289. is in running the Switcher entirely from ARexx scripts without allowing
  290. input from the Switcher interface (keyboard, mouse, etc.) to interfere with
  291. the execution of the ARexx script.  Only diskchanges will still be
  292. processed.
  293.  
  294.         Switcher( DIIM )
  295.         Switcher( ENIM )
  296. The above commands are for disabling/enabling rendering, the SoftSprite
  297. system, and the mouse and keyboard IDCMP.  These calls can be used to speed
  298. up the processing of ARexx switcher commands at the expense of visual
  299. feedback of the transition.  When enabled, the Switcher display will be
  300. completely redrawn.
  301.  
  302.         Switcher( MEMC ,'L')
  303. The above command returns the amount of free CHIP memory or the largest
  304. CHIP chunk if the 'L'  option is used.  This command is ARexx dependent.
  305.  
  306.         Switcher( MEMF ,'L')
  307. The above command returns the amount of free FAST only memory or the
  308. largest FAST only chunk if the 'L'  option is used.  This command is ARexx
  309. dependent.
  310.  
  311.         Switcher( CKTP )
  312.         Switcher( CKCG )
  313.         Switcher( CKLW )
  314. The above commands check for the existence of ToasterPaint, CG, and
  315. LightWave respectively.  They return a 1 if the program entity is currently
  316. loaded and 0 if not.  These commands are ARexx dependent.
  317.  
  318.         Switcher( LDTP )
  319.         Switcher( LDCG )
  320.         Switcher( LDLW )
  321. The above commands attempt to load ToasterPaint, CG, or LightWave
  322. respectively if those program entities are not already loaded.  These
  323. commands can be dangerous if the load fails and a requester comes up,
  324. hanging ARexx.
  325.  
  326.         Switcher( DPTP )
  327.         Switcher( DPCG )
  328.         Switcher( DPLW )
  329. The above commands will unload ToasterPaint, CG, or LightWave respectively
  330. if those program entities are loaded.
  331.  
  332.         Switcher( STTP )
  333. This command will enter ToasterPaint if and only if it is currently active,
  334. otherwise this command is a NOP.  Once entering ToasterPaint, your ARexx
  335. message will not be returned until ToasterPaint exits back to the Switcher.
  336. So be careful that you don't hang yourself.
  337.  
  338.         Switcher( OGPI )
  339. This command causes an output GPI trigger to occur in accordance to the
  340. current settings of the GPI system.  This command is a NOP if GPI
  341. triggering is disabled.  Tech note:  GPI output occurs on pin 9 of the
  342. second gameport (potentiometer circuit).
  343.  
  344.         Switcher( TERM, <mask> )
  345. This command sets the termination for the four video inputs.  The mask will
  346. be a number from 0 to 15 whose bits (0-3) control the termination setting for
  347. inputs 1-4.
  348.  
  349.         Switcher( SRGB, <filename>,<field>,<bank>)
  350. This command saves the contents of one of the digital video buffer to a
  351. standard IFF24 type rgb file. The filename should include the complete file
  352. path. The bank argument should be 0 for DV1 and 1 for DV2. Field selects
  353. which of the 4 fields (0-3) of video stored in the frame buffer should be
  354. saved. Setting field to 4 will initiate motion removal and save 2 fields.
  355. Setting field to 5 will save a full 4-field 'color frame'. This is the best
  356. quality save.
  357. NOTE: Not all of these settings are currently implemented .
  358.  
  359.         Switcher(LRGB,<filename>,<bank>)
  360. This command loads an RGB image into the specified digital video buffer.
  361. The filename should include the complete file path.  The bank argument
  362. should be 0 for DV1 and 1 for DV2.
  363. Note: This feature will load framestores as well.
  364.  
  365.         Switcher(FACE,<monitors>)
  366. This command sets the interface to 2 monitor or 3 monitor mode, when
  367. monitor is 2 or 3 respectively.
  368.  
  369.         Switcher(GROF)
  370. This command turns off the image hilighting system and software
  371. mouse pointer.  Each call to this function MUST be matched with
  372. exactly one (1) call to the GRON function.  After this call no
  373. interface elements will be hilighted. The function returns a pointer to
  374. the bitmap structure used by the screen.
  375. NOTE: Now (>4.03) checks to see if image hilighting is ALREADY off and just
  376. returns if that is so.  If GROF really happens (if image hilighting
  377. is ON when you call GROF) then you will get the pointer to the bitmap
  378. structure of the screen as a return value.  If GROF doesn't happen
  379. because hilighting is ALREADY off, you will get a return value of 0
  380. instead of the bitmap structure pointer value.
  381.  
  382.         Switcher(GRON)
  383. This command turns on the image hilighting system and software mouse
  384. pointer after a GROF.  Each call to this function MUST be matched with
  385. exactly one (1) prior call to the GROF function.
  386. NOTE: Now (>4.03) checks that image hilighting is indeed OFF before
  387. doing anything.  If image hilighting is OFF when you call GRON then
  388. GRON will turn it back ON.  If image hilighting is already ON when
  389. you call GRON, then it does nothing (but reports no error, either).
  390.